home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload Trio 2 / Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO / dir36 / getkey16.zip / GETKEY.TXT < prev    next >
Text File  |  1993-08-21  |  11KB  |  247 lines
  1. August 21, 1993               GETKEY ver. 1.6
  2.                                     by
  3.                               Matthew G. Moody
  4.                               206 Waterwood Dr.
  5.                               Goose Creek, SC 29445
  6.                               (803) 572-4868
  7.                               CIS 72607,3461
  8.  
  9.  
  10.   This is my seventh update to GETKEY.  The first version simply retrieved a 
  11. key from the keyboard and returned a value to dos that ERRORLEVEL could 
  12. detect.  My brother asked if MSDOS 6 already had a batch file command that 
  13. would do this already.  So I looked into it and sure enough, there was.  
  14. That command is CHOICE.  So I set about writing a probram to mimic it, 
  15. mainly for the challenge.  The second version of GETKEY followed CHOICE 
  16. exactly, with the exception of the time delay parameter.  The third 
  17. version included that parameter.  The fourth revision accepted menu items
  18. and set the display colors for the menu. 
  19.   
  20.   The fifth revision takes the tilde prefixed characters in the menu items
  21. and forces them to be the valid keys to accept, in other words, the /c 
  22. switch is ignored when the program encounters a tilde character (~) within
  23. an /m switch.  Also, I changed the key prompt to output in highlight. To make
  24. this more like DOS's CHOICE when you press a valid choice it is displayed at
  25. the end of the prompt string.
  26.  
  27.   The sixth was a minor revision to solve the bug that occured when using the 
  28. timed response switch.  It was displaying "null pointer assignment" after the 
  29. program ended.  That was a tricky little bugger to find.  
  30. Thanks to Glenn R. Sogge for his help in locating that sneaky rascal.
  31.  
  32.   This revision brings the capability to read in a text file with the command
  33. switches listed in it so the user may create longer menus.
  34.   
  35.   GETKEY waits for the user to choose one of a set of choices.
  36.  
  37. The syntax for GETKEY is:
  38.  
  39. GETKEY [/|-C[:]choices] [/|-N] [/|-S] [/|-T[:]c,nn] [/|-D[:]b,f,h] ["text"]
  40.        [/|-M"~menu 1"] ... [/|-Mx,y"menu ~n] [/|-Fmenufile.gks]
  41. NOTE: You may use - or / to delimit parameters.
  42.  
  43. /C[:]choices     Specifies allowable keys. Default is YN
  44. /N               Do not display choices and ? at end of prompt string.
  45. /S               Treat choice keys as case sensitive.
  46. /T[:]c,nn        Default choice to c after nn seconds
  47. /D[:]b,f,h       Display attributes for background, foreground, and 
  48.                  highlight.
  49. /M[x,y]"menu ~1" Text string to display as a menu item at x,y coordinates.
  50. /Fmenufile.gks   Menu file with arguments (It is assumed the file has the 
  51.                  .gks extension.)
  52. "text"           Prompt string to display
  53.  
  54. ERRORLEVEL is set to offset of key user presses in choices.
  55.  
  56.   Because GETKEY is not the same as choice any longer, this could be useful
  57. to everyone.  If you have any ideas on how to improve it further please let me 
  58. know via "The Penetentiary BBS", (706) 737-5631 (my brother runs that board so 
  59. you can leave a private message with him or me.  If you found this on a BBS 
  60. in the Charleston area, you can leave a note for me where you found this. Also 
  61. you can leave a message to me on CompuServe.  My CompuServe address is shown 
  62. above.
  63.  
  64.   Please let me know what you think of GETKEY this is the first program I have
  65. written to be used by anyone other than myself.  Also, I am open to suggestions
  66. for improvements, add-ons, or what-have-you.
  67.  
  68.   GETKEY goes beyond merely replacing ASK.COM.  With it, you aren't limited 
  69. just to posing yes/no questions.  For example, using GETKEY, you could ask 
  70. this question in your batch:
  71.  
  72. Select setup: Command line, DOS Shell, Windows [C,D,W]?
  73.   
  74.   The command for the above would be:
  75.   GETKEY "Select setup: Command line, DOS Shell, Windows " /C:CDW
  76.  
  77.   The /C switch tells GETKEY what keys for which to wait.  In the case above, 
  78. those would be C, D, and W, which are displayed as a prompt in GETKEY's 
  79. output.  Because the C key comes first, it will generate an errorlevel of 1, D
  80. will generate 2, and W will be 3.
  81.   To test for these errorlevels in your batch files, you will need to stack
  82. your IF ERRORLEVEL statements carefully.  The reason for this is because IF
  83. ERRORLEVEL tests out positive when the value returned is equal to or greater 
  84. than the value specified in the IF ERRORLEVEL test.  This can be tricky, as 
  85. the following example shows:
  86.  
  87.           IF ERRORLEVEL 2 DOSSHELL
  88.  
  89.   Here, the DOSSHELL command is executed when an errorlevel of 2 or greater is
  90. returned.  So, if the errorlevel is equal to 3 or 4 or 5, on up, the DOSSHELL 
  91. command is executed.  That's probably not what you want.
  92.   To ensure that the proper errorlevel value is found, you can use the follow-
  93. ing batch-file statement:
  94.  
  95.     IF ERRORLEVEL X IF NOT ERRORLEVEL X+1 command
  96.  
  97.   This statement executes the command when an errorlevel value of X is 
  98. returned -- no more, no less.
  99.  
  100.  
  101.   Perhaps the handiest feature of the GETKEY command is its timeout function.
  102. This lets your batch files proceed with automatic selections when the user is
  103. too pokey to type them.  Here is an example using the timeout function:
  104.  
  105.     GETKEY /C:ABCD /T:C,60 "Your selection "
  106.  
  107.   If the user doesn't type anything for more than 60 seconds, the computer
  108. selects option C.  GETKEY then generates an errorlevel value of 3, and the 
  109. batch file continues. This works because of GETKEY's /T switch.  The /T switch
  110. is followed by a colon, plus the key GETKEY will "press" automatically after
  111. 60 seconds of inactivity.  This is really handy.  By using GETKEY with its /T 
  112. timeout in AUTOEXEC.BAT, you can have the computer start up without your 
  113. input, for example after a power blackout or if you reset but don't want to 
  114. sit, watch, and provide information while the computer starts up.
  115.  
  116.   An interesting side effect of the /T switch is that you can use GETKEY to 
  117. insert deliberate pauses into your batch files.  For example, employing the
  118. command in this format:
  119.  
  120.       GETKEY /T:Y,60 /N
  121.  
  122. uses the /T switch to insert a 60-second pause into a batch file.  You could 
  123. use this line after a message display instead of the PAUSE command with its
  124. boring "Press any key" message.  With GETKEY, the pause is brief, and the 
  125. program continues "automatically."  The /N switch suppresses the prompt and
  126. because no text was specified, you will have a blank line on the screen.
  127.  
  128.   To make your screen more colorful use GETKEY's /D switch.  For example, to
  129. make a blue background with yellow foreground and white highlighted letters
  130. use the following format:
  131.  
  132.       GETKEY /D:1,14,15 "Your selection "
  133.  
  134.   Valid color values are shown in the table below.
  135.  
  136.               ╔═════════════════════╤════════════════════════╗
  137.               ║    Background       │  Foreground/Highlight  ║
  138.               ╟─────────────────────┼────────────────────────╢
  139.               ║   Black         0   │   Black          0     ║
  140.               ║   Blue          1   │   Blue           1     ║
  141.               ║   Green         2   │   Green          2     ║
  142.               ║   Cyan          3   │   Cyan           3     ║
  143.               ║   Red           4   │   Red            4     ║
  144.               ║   Magenta       5   │   Magenta        5     ║
  145.               ║   Brown         6   │   Brown          6     ║
  146.               ║   Light Gray    7   │   Light Gray     7     ║
  147.               ║                     │   Dark Gray      8     ║
  148.               ║                     │   Light Blue     9     ║
  149.               ║                     │   Light Green   10     ║
  150.               ║                     │   Light Cyan    11     ║
  151.               ║                     │   Light Red     12     ║
  152.               ║                     │   Light Magenta 13     ║
  153.               ║                     │   Yellow        14     ║
  154.               ║                     │   White         15     ║
  155.               ║                     │   Blink        128     ║
  156.               ╚═════════════════════╧════════════════════════╝
  157.  
  158.     Add 128 to foreground or highlight to create blink i.e. for blinking
  159. yellow highlight use /d,,142.
  160.  
  161.   Now, you are probably asking, where do the highlighted letters come into 
  162. play?  That's the biggest part that MicroSoft(R) left out! Simply by using 
  163. GETKEY's menu switch /M, you can have the key character you want the user to
  164. press for selecting the menu item.  You can have as many /M switches as you 
  165. have command line room for, and with DOS, remember that is 255.
  166.   The syntax for the menu switch is:
  167.  
  168.       GETKEY /M"~Windows" /M"~DOS Shell" /M"~Command line"
  169.  
  170. The '~' tells GETKEY the following character is to be a highlighted character.
  171. The output would appear as below:
  172.  
  173. Command line
  174. DOS Shell
  175. Windows
  176.  
  177. [C,D,W] ?
  178.  
  179. because the program sorts the menu items before displaying them.  Because of 
  180. this be sure to test your batch files without testing for ERRORLEVEL to see 
  181. what order the menu will display.  (Menu order affects the order of valid 
  182. keys!)  Also remember the tilde character falls after lower case letters in
  183. the ASCII character set, so if you use the following command:
  184.  
  185.     
  186. GETKEY /M"~Windows" /M"C~opy a file" /M"~Command line"
  187.  
  188. this would be your output:
  189.  
  190. Copy a file
  191. Command line
  192. Windows
  193.  
  194. [O,C,W] ?
  195.  
  196. not this:
  197.  
  198. Command line
  199. Copy a file
  200. Windows
  201.  
  202. [C,O,W] ?
  203.  
  204. Also, you can have more than one valid key per menu item:
  205.  
  206.     GETKEY -m"~1. ~Windows" -m"~2. C~opy a file" -m"~3. ~Command line" 
  207.  
  208. 1. Windows
  209. 2. Copy a file
  210. 3. Command line
  211.  
  212. [1,W,2,O,3,C] ?
  213.  
  214. just be sure to use:
  215.  
  216.     IF ERRORLEVEL x IF NOT ERRORLEVEL x+2 GOTO command
  217.  
  218.   The other change in the /M switch is placing menus on screen locations:
  219.  
  220. GETKEY "Your selection " -m5,5"~1. ~Windows" -m5,6"~2. C~opy a file" -m5,7"~3. ~Command line" /s
  221.  
  222. (screen line #4 y coordinate) 
  223.     1. Windows
  224.     2. Copy a file
  225.     3. Command line
  226.     ^─────────────────── (row #5 x coordinate)
  227. Your selection [1,W,2,o,3,C] ? 
  228.     
  229.   Because the program sorts the menu items before displaying them, test your
  230. batch file without "IF ERRORLEVEL x IF NOT ERRORLEVEL x GOTO command" lines
  231. so you can see what order they will be displayed, also, be sure not to use 
  232. the /n switch so you can see the order of the selection keys.  
  233.  
  234.   The /f switch looks for the file named and reads the arguments listed.  The
  235. file format is simple one argument per line.  You cannot use the /f switch
  236. in the file.
  237.  
  238. (Sample file listing.)
  239. "Your selection " 
  240. -m5,5"~1. ~Windows" 
  241. -m5,6"~2. C~opy a file" 
  242. -m5,7"~3. ~Command line" 
  243. /s
  244.  
  245.   There are nine batch files demonstrating how you could use GETKEY in your 
  246. batch files.  Good luck.
  247.